排序 ¶

當顯示多行資料時，通常需要根據終端使用者指定的某些欄位對資料進行排序。Yii 使用 yii\data\Sort 物件來表示排序架構的資訊。特別是：

• attributes 指定可以對資料進行排序的屬性。屬性可以簡單到像 模型屬性。它也可以是複合屬性，通過組合多個模型屬性或資料庫欄位。更多詳細資訊將在下面給出。
• attributeOrders 給出每個屬性當前請求的排序方向。
• orders 以底層欄位的形式給出排序方向。

要使用 yii\data\Sort，首先宣告哪些屬性可以排序。然後從 attributeOrders 或 orders 中檢索當前請求的排序資訊，並使用它們來自訂資料查詢。例如，

use yii\data\Sort;

$sort = new Sort([
    'attributes' => [
        'age',
        'name' => [
            'asc' => ['first_name' => SORT_ASC, 'last_name' => SORT_ASC],
            'desc' => ['first_name' => SORT_DESC, 'last_name' => SORT_DESC],
            'default' => SORT_DESC,
            'label' => 'Name',
        ],
    ],
]);

$articles = Article::find()
    ->where(['status' => 1])
    ->orderBy($sort->orders)
    ->all();

在上面的範例中，為 Sort 物件宣告了兩個屬性：age 和 name。

age 屬性是一個簡單屬性，對應於 Article Active Record 類別的 age 屬性。它等效於以下宣告

'age' => [
    'asc' => ['age' => SORT_ASC],
    'desc' => ['age' => SORT_DESC],
    'default' => SORT_ASC,
    'label' => Inflector::camel2words('age'),
]

name 屬性是一個複合屬性，由 Article 的 first_name 和 last_name 定義。它是使用以下陣列結構宣告的

• asc 和 desc 元素分別指定如何按升序和降序方向對屬性進行排序。它們的值表示實際的欄位和資料應按其排序的方向。您可以指定一個或多個欄位來指示簡單排序或複合排序。
• default 元素指定最初請求時應按其排序屬性的方向。它預設為升序，這表示如果之前未排序，並且您請求按此屬性排序，則資料將按此屬性以升序排序。
• label 元素指定在調用 yii\data\Sort::link() 以建立排序連結時應使用的標籤。如果未設定，將調用 yii\helpers\Inflector::camel2words() 以從屬性名稱生成標籤。請注意，它不會進行 HTML 編碼。

資訊：您可以直接將 orders 的值饋送到資料庫查詢以建立其 ORDER BY 子句。不要使用 attributeOrders，因為某些屬性可能是複合屬性，並且無法被資料庫查詢識別。

您可以調用 yii\data\Sort::link() 來生成一個超連結，終端使用者可以點擊該連結以請求按指定的屬性對資料進行排序。您也可以調用 yii\data\Sort::createUrl() 來建立可排序的 URL。例如，

// specifies the route that the URL to be created should use
// If you do not specify this, the currently requested route will be used
$sort->route = 'article/index';

// display links leading to sort by name and age, respectively
echo $sort->link('name') . ' | ' . $sort->link('age');

// displays: /index.php?r=article%2Findex&sort=age
echo $sort->createUrl('age');

yii\data\Sort 檢查 sort 查詢參數以確定請求排序的屬性。當查詢參數不存在時，您可以通過 yii\data\Sort::$defaultOrder 指定預設排序。您也可以通過配置 sortParam 屬性來自訂查詢參數的名稱。